Using the Toggle Button Group nodes

Use the Toggle Button Group nodes to allow users to select only one option from a set of options that are mutually exclusive. Toggle buttons in a toggle button group behave like radio buttons, where only one toggle button can be active at a time. Use Toggle Button Group 3D to group 3D toggle buttons in 3D space, and Toggle Button Group 2D to group 2D toggle buttons in 2D space.

A toggle button group is a node that can contain Toggle Button nodes and manages their states, but does not provide a visual shape.
When a Toggle Button node in a Toggle Button Group has focus, it receives click input from the keyboard keys Space, Enter, and Enter on the numeric pad by default. Use scripting functions to get and set the node that currently has focus in the project. See Scripting reference and Using triggers.

Creating a toggle button group

To create a toggle button group:

In the Project press Alt and right-click the node where you want to create a Toggle Button Group and select either Toggle Button Group 2D, or Toggle Button Group 3D.
Note that you can create a 3D node only inside 3D nodes, and 2D node only inside 2D nodes.
In the Project in the Toggle Button Group create a layout that arranges the Toggle Button nodes in the Toggle Button Group node.
For example, if you created a Toggle Button Group 2D, create a Stack Layout 2D node, if you created a Toggle Button Group 3D, create a Stack Layout 3D node. See Using the Stack Layout nodes.
In the Project add Toggle Button nodes to the layout you created in the previous step.
For example, if you created a 2D toggle button group with a Stack Layout 2D node, add several Toggle Button 2D nodes, if you created a 3D toggle button group with a Stack Layout 3D node, add several Toggle Button 3D nodes. See Using the Toggle Button nodes.
In the Project select the Toggle Button nodes you added to the Toggle Button Group, in the Properties click , and add to each Toggle Button the Index in Group property.
Kanzi uses the Index in Group property to keep track of which Toggle Button is selected in a Toggle Button Group node. When the value of the Index in Group property is -1 the Toggle Button Group node sets the index for that Toggle Button.
(Optional) In the Project select one of the Toggle Button nodes in the Toggle Button Group node and in the Properties add and set the Toggle State property to 1.
For example, select the first Toggle Button node. You set that Toggle Button to be toggled on when the application starts.

In the Preview when you click the Toggle Button nodes in the Toggle Button Group node, the Toggle Button Group node toggles the states in Toggle Button nodes.

Setting off a trigger when a Toggle Button in a Toggle Button Group is toggled

You can set off a trigger when the user toggles the state of a Toggle Button in a Toggle Button Group. For example, you can execute a script which sets focus to a user interface element based on which a Toggle Button was toggled.

To set off a trigger when a Toggle Button in a Toggle Button Group is toggled:

In the Project select the Toggle Button Group to which you want to add a trigger which is set off when the user toggles the state of a Toggle Button in that Toggle Button Group. See Creating a toggle button group.
In the Node Components > Triggers section right-click, select Add Trigger, and select the Toggle Button Group: Toggled trigger.
In the Node Components > Triggers section click the Add dropdown menu for the trigger you added in the previous step and select an action.
For example, select the Write Log action and enter a message you want to write to the Log window when the trigger is set off. The Write Log action is useful when you want to verify that the node received the input.
To make the Toggle Button Group: Toggled trigger intercept messages from all Toggle Button nodes in the Toggle Button Group, in the Node Components under the Toggle Button Group: Toggled trigger, click Trigger Settings, and in the Trigger Settings Editor, set Message Source to <No Item>.
Use the Message Source property to set which trigger messages this trigger handles. See Setting the handling of trigger messages.

Now when you change the toggle state of any of the buttons in the Toggle Button Group, Kanzi prints to the Log window the message you entered as the value of the Log Message property.
To open the Log window, in the main menu select Window > Log.

Setting the appearance of a Toggle Button Group 2D node

To set the appearance of 2D nodes:

You can fill 2D nodes with a solid color, a texture, or a material. See Adjusting the appearance of 2D nodes.
You can rotate a 2D node around all three axes to create a 3D perspective effect. See Creating a 3D perspective effect for 2D nodes.
You can apply custom rendering to 2D nodes to create post-processing effects. See Applying custom rendering to 2D nodes.

Using the Toggle Button Group 3D node in the API

To create a Toggle Button Group 3D node with three toggle buttons:

// Create a Toggle Button Group 3D named Toggle button group and add it to the scene.
ToggleButtonGroup3DSharedPtr toggleButtonGroup3D = ToggleButtonGroup3D::create(domain, "Toggle button group");
scene->addChild(toggleButtonGroup3D);
// Create a Stack Layout 3D named Stack layout and add it to the Toggle button group.
// This stack layout is used only for arranging the items in the Toggle button group.
StackLayout3DSharedPtr stackLayout3D = StackLayout3D::create(domain, "Stack layout");
toggleButtonGroup3D->addChild(stackLayout3D);

// Create three toggle buttons and add them to the Stack layout.
ToggleButton3DSharedPtr buttons[3];

for (kzUint i = 0; i < 3; ++i)
{
    buttons[i] = ToggleButton3D::create(domain, "Toggle button");
    // Setting the Button Group Index property to -1, which tells the Toggle button group
    // to set the index of the toggle button.
    buttons[i]->setIndexInGroup(-1);
    stackLayout3D->addChild(buttons[i]);
}

// Print the index of the toggled button to show that the last button is toggled.
std::cout << toggleButtonGroup3D->getCurrentButtonIndex() << endl;

// Toggle the first toggle button.
buttons[0]->setToggleState(1);

// Print the index of the toggled button to show that the first button is toggled.
std::cout << toggleButtonGroup3D->getCurrentButtonIndex() << endl;

For details, see the ToggleButtonGroup3D class in the API reference.

Using the Toggle Button Group 2D node in the API

To create a Toggle Button Group 2D node with three toggle buttons:

// Create a Toggle Button Group 2D named Toggle button group and add it to the scene.
ToggleButtonGroup2DSharedPtr toggleButtonGroup2D = ToggleButtonGroup2D::create(domain, "Toggle button group");
viewportNode->addChild(toggleButtonGroup2D);
// Create a Stack Layout 2D named Stack layout and add it to the Toggle button group.
// This stack layout is used only for arranging the items in the Toggle button group.
StackLayout2DSharedPtr stackLayout2D = StackLayout2D::create(domain, "Stack layout");
toggleButtonGroup2D->addChild(stackLayout2D);

// Create three toggle buttons and add them to the Stack layout.
ToggleButton2DSharedPtr buttons[3];

for (kzUint i = 0; i < 3; ++i)
{
    buttons[i] = ToggleButton2D::create(domain, "toggle button");
    // Setting the Button Group Index property to -1, which tells the Toggle button group
    // to set the index of the toggle button.
    buttons[i]->setIndexInGroup(-1);
    stackLayout2D->addChild(buttons[i]);
}

// Print the index of the toggled button to show that the last button is toggled.
std::cout << toggleButtonGroup2D->getCurrentButtonIndex() << endl;

// Toggle the first toggle button.
buttons[0]->setToggleState(1);

// Print the index of the toggled button to show that the first button is toggled.
std::cout << toggleButtonGroup2D->getCurrentButtonIndex() << endl;

For details, see the ToggleButtonGroup2D class in the API reference.

Toggle Button Group property types and messages

For lists of the available property types and messages for the Toggle Button Group nodes, see Toggle button group 2D and Toggle button group 3D.